home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 85 / CD Actual 85 Febrero 2004.iso / Experto / Apache / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F251749_apr_hooks.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-08-15  |  11.1 KB  |  312 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_HOOKS_H
  56. #define APR_HOOKS_H
  57.  
  58. #include "apu.h"
  59. /* For apr_array_header_t */
  60. #include "apr_tables.h"
  61.  
  62. /**
  63.  * @file apr_hooks.h
  64.  * @brief Apache hook functions
  65.  */
  66.  
  67. #ifdef __cplusplus
  68. extern "C" {
  69. #endif
  70. /**
  71.  * @defgroup APR_Util_Hook Hook Functions
  72.  * @ingroup APR_Util
  73.  * @{
  74.  */
  75. /** macro to return the prototype of the hook function */    
  76. #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  77. link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
  78.  
  79. /** macro to declare the hook correctly */    
  80. #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
  81. typedef ret ns##_HOOK_##name##_t args; \
  82. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
  83.                                       const char * const *aszPre, \
  84.                                       const char * const *aszSucc, int nOrder); \
  85. link##_DECLARE(ret) ns##_run_##name args; \
  86. APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
  87. typedef struct ns##_LINK_##name##_t \
  88.     { \
  89.     ns##_HOOK_##name##_t *pFunc; \
  90.     const char *szName; \
  91.     const char * const *aszPredecessors; \
  92.     const char * const *aszSuccessors; \
  93.     int nOrder; \
  94.     } ns##_LINK_##name##_t;
  95.  
  96. /** macro to declare the hook structure */    
  97. #define APR_HOOK_STRUCT(members) \
  98. static struct { members } _hooks;
  99.  
  100. /** macro to link the hook structure */
  101. #define APR_HOOK_LINK(name) \
  102.     apr_array_header_t *link_##name;
  103.  
  104. /** macro to implement the hook */
  105. #define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  106. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
  107.                                       const char * const *aszSucc,int nOrder) \
  108.     { \
  109.     ns##_LINK_##name##_t *pHook; \
  110.     if(!_hooks.link_##name) \
  111.     { \
  112.     _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \
  113.     apr_hook_sort_register(#name,&_hooks.link_##name); \
  114.     } \
  115.     pHook=apr_array_push(_hooks.link_##name); \
  116.     pHook->pFunc=pf; \
  117.     pHook->aszPredecessors=aszPre; \
  118.     pHook->aszSuccessors=aszSucc; \
  119.     pHook->nOrder=nOrder; \
  120.     pHook->szName=apr_hook_debug_current; \
  121.     if(apr_hook_debug_enabled) \
  122.     apr_hook_debug_show(#name,aszPre,aszSucc); \
  123.     } \
  124.     APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  125.     { \
  126.         return _hooks.link_##name; \
  127.     }
  128.  
  129. /**
  130.  * Implement a hook that has no return code, and therefore runs all of the
  131.  * registered functions
  132.  * @param ns The namespace prefix of the hook functions
  133.  * @param link The linkage declaration prefix of the hook
  134.  * @param name The name of the hook
  135.  * @param args_decl The declaration of the arguments for the hook
  136.  * @param args_use The names for the arguments for the hook
  137.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  138.  * provide export linkage from the module that IMPLEMENTs the hook, and
  139.  * import linkage from external modules that link to the hook's module.
  140.  */
  141. #define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \
  142. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  143. link##_DECLARE(void) ns##_run_##name args_decl \
  144.     { \
  145.     ns##_LINK_##name##_t *pHook; \
  146.     int n; \
  147. \
  148.     if(!_hooks.link_##name) \
  149.     return; \
  150. \
  151.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  152.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  153.     pHook[n].pFunc args_use; \
  154.     }
  155.  
  156. /* FIXME: note that this returns ok when nothing is run. I suspect it should
  157.    really return decline, but that breaks Apache currently - Ben
  158. */
  159. /**
  160.  * Implement a hook that runs until one of the functions returns something
  161.  * other than OK or DECLINE
  162.  * @param ns The namespace prefix of the hook functions
  163.  * @param link The linkage declaration prefix of the hook
  164.  * @param ret Type to return
  165.  * @param name The name of the hook
  166.  * @param args_decl The declaration of the arguments for the hook
  167.  * @param args_use The names for the arguments for the hook
  168.  * @param ok Success value
  169.  * @param decline Decline value
  170.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  171.  * provide export linkage from the module that IMPLEMENTs the hook, and
  172.  * import linkage from external modules that link to the hook's module.
  173.  */
  174. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \
  175. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  176. link##_DECLARE(ret) ns##_run_##name args_decl \
  177.     { \
  178.     ns##_LINK_##name##_t *pHook; \
  179.     int n; \
  180.     ret rv; \
  181. \
  182.     if(!_hooks.link_##name) \
  183.     return ok; \
  184. \
  185.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  186.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  187.     { \
  188.     rv=pHook[n].pFunc args_use; \
  189. \
  190.     if(rv != ok && rv != decline) \
  191.         return rv; \
  192.     } \
  193.     return ok; \
  194.     }
  195.  
  196.  
  197. /**
  198.  * Implement a hook that runs until the first function returns something
  199.  * other than the value of decline
  200.  * @param ns The namespace prefix of the hook functions
  201.  * @param link The linkage declaration prefix of the hook
  202.  * @param name The name of the hook
  203.  * @param ret Type to return
  204.  * @param args_decl The declaration of the arguments for the hook
  205.  * @param args_use The names for the arguments for the hook
  206.  * @param decline Decline value
  207.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  208.  * provide export linkage from the module that IMPLEMENTs the hook, and
  209.  * import linkage from external modules that link to the hook's module.
  210.  */
  211. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
  212. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  213. link##_DECLARE(ret) ns##_run_##name args_decl \
  214.     { \
  215.     ns##_LINK_##name##_t *pHook; \
  216.     int n; \
  217.     ret rv; \
  218. \
  219.     if(!_hooks.link_##name) \
  220.     return decline; \
  221. \
  222.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  223.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  224.     { \
  225.     rv=pHook[n].pFunc args_use; \
  226. \
  227.     if(rv != decline) \
  228.         return rv; \
  229.     } \
  230.     return decline; \
  231.     }
  232.  
  233.     /* Hook orderings */
  234. /** run this hook first, before ANYTHING */
  235. #define APR_HOOK_REALLY_FIRST    (-10)
  236. /** run this hook first */
  237. #define APR_HOOK_FIRST        0
  238. /** run this hook somewhere */
  239. #define APR_HOOK_MIDDLE        10
  240. /** run this hook after every other hook which is defined*/
  241. #define APR_HOOK_LAST        20
  242. /** run this hook last, after EVERYTHING */
  243. #define APR_HOOK_REALLY_LAST    30
  244.  
  245. /**
  246.  * The global pool used to allocate any memory needed by the hooks.
  247.  */ 
  248. APU_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool;
  249.  
  250. /** @deprecated @see apr_hook_global_pool */
  251. APU_DECLARE_DATA extern apr_pool_t *apr_global_hook_pool;
  252.  
  253. /**
  254.  * A global variable to determine if debugging information about the
  255.  * hooks functions should be printed
  256.  */ 
  257. APU_DECLARE_DATA extern int apr_hook_debug_enabled;
  258.  
  259. /** @deprecated @see apr_hook_debug_enabled */
  260. APU_DECLARE_DATA extern int apr_debug_module_hooks;
  261.  
  262. /**
  263.  * The name of the module that is currently registering a function
  264.  */ 
  265. APU_DECLARE_DATA extern const char *apr_hook_debug_current;
  266.  
  267. /** @deprecated @see apr_hook_debug_current */
  268. APU_DECLARE_DATA extern const char *apr_current_hooking_module;
  269.  
  270. /**
  271.  * Register a hook function to be sorted
  272.  * @param szHookName The name of the Hook the function is registered for
  273.  * @param aHooks The array which stores all of the functions for this hook
  274.  */
  275. APU_DECLARE(void) apr_hook_sort_register(const char *szHookName, 
  276.                                         apr_array_header_t **aHooks);
  277. /**
  278.  * Sort all of the registerd functions for a given hook
  279.  */
  280. APU_DECLARE(void) apr_hook_sort_all(void);
  281.  
  282. /** @deprecated @see apr_hook_sort_all */
  283. APU_DECLARE(void) apr_sort_hooks(void);
  284.  
  285. /**
  286.  * Print all of the information about the current hook.  This is used for
  287.  * debugging purposes.
  288.  * @param szName The name of the hook
  289.  * @param aszPre All of the functions in the predecessor array
  290.  * @param aszSucc All of the functions in the successor array
  291.  */
  292. APU_DECLARE(void) apr_hook_debug_show(const char *szName,
  293.                                       const char * const *aszPre,
  294.                                       const char * const *aszSucc);
  295.  
  296. /** @deprecated @see apr_hook_debug_show */
  297. APU_DECLARE(void) apr_show_hook(const char *szName,
  298.                                 const char * const *aszPre,
  299.                                 const char * const *aszSucc);
  300.  
  301. /**
  302.  * Remove all currently registered functions.
  303.  */
  304. APU_DECLARE(void) apr_hook_deregister_all(void);
  305.  
  306. /** @} */
  307. #ifdef __cplusplus
  308. }
  309. #endif
  310.  
  311. #endif /* APR_HOOKS_H */
  312.